Connectivity Software User's Guide and Reference
Common Data Model For Sparkplug
Rapid Toolkit for Sparkplug is a library of many objects belonging to various categories.
This article describes the aspects and parts of the Rapid Toolkit for Sparkplug data model that are common for consumers (host applications) and providers (edge nodes and devices). For consumer- and producer-specific data models, see:
Sparkplug data transfer objects encapsulate the data used in Sparkplug, and carry them inside the toolkit and to/from your code. Sparkplug data transfer objects operations do not affect anything external (and not passed to) to them; they simply care of their own data for the purpose of storage, retrieval, comparisons, serialization/deserialization and such.
Data transferred in Sparkplug consist of the actual value, and associated timestamp. The timestamp represents the time at which the value of a metric was captured. In addition, there is a "transient" flag; transient data can be considered those that are of interest to a host application(s) but should not be stored in a historian.
When the Sparkplug producer (edge node or device) sends out information or receives commands, it is always Sparkplug data in some form. Conversely, when the Sparkplug consumer (host application) receives information or sends out commands, it is always Sparkplug data in some form.
In Rapid Toolkit for Sparkplug, Sparkplug data is represented by the SparkplugData Class and its properties. The actual value is stored in its Value Property. The timestamp is, in principle, optional, and a missing timestamp is represented by DateTime.MinValue. However, for many usages, the Sparkplug specification makes the presence of the timestamp mandatory in the Sparkplug data.
Sparkplug metric data is an extended form of the Sparkplug data. In addition to the actual data value, timestamp and the transient flag, it also contains the data type, historical flag, and, when applicable, template definition name. In Rapid Toolkit for Sparkplug, Sparkplug metric data is represented by the SparkplugMetricData Class and its properties.
The data type is a value from the SparkplugDataType Enumeration. The historical flag denotes that the metric should not be considered a real time/current value, and is sent after it was acquired from a device or edge node.
The reason why Sparkplug metric data is distinguished from the plain Sparkplug data is in order to separate the properties that can be handled by the toolkit. The additional properties in the Sparkplug metric data can - in some cases - be handled by the toolkit, and in such cases your code only needs to deal with the Sparkplug data.
Sparkplug metadata is used to describe different types of binary data transferred by a Sparkplug metric. In Rapid Toolkit for Sparkplug, Sparkplug metadata is represented by the SparkplugMetadata Class and is properties.
When the Sparkplug producer (edge node or device) publishes a metric, it has to include the Sparkplug metadata describing the metric in the birth message (Rapid Toolkit for Sparkplug takes care of it). The Sparkplug consumer (host application) can then make use of the metadata to make decisions about further processing of the data, for display purposes, etc.
The data type of the metric is stored in the DataType Property and is probably the most important piece of metadata. Note that in the Sparkplug protocol, the data type is transferred in parallel to the metadata; however, it logically belongs to the metadata, and that is why it appears in the SparkplugMetadata Class.
In Sparkplug, data for one or more metrics are transferred together in one message. The Sparkplug payload, represented in Rapid Toolkit for Sparkplug by the SparkplugPayload Class, contains a collection of Sparkplug metrics, and some additional data.
In Rapid Toolkit for Sparkplug, you can either deal with metrics individually, or you can choose to process or generate the whole payload. When you deal with metrics individually, the toolkit will assemble the payload from the metrics for you for sending purposes, and/or it will disassemble the payload to its constituent metrics when receiving. This generally easier gives easier and shorter code. You may want to deal with the payload as a whole e.g. if the payload represents a "dataset" with certain metrics whose data always belong together.
The Sparkplug payload acts as a collection of payload elements. Each payload element is a key-value pair, where the key is the name of the metric, and the value is a metric element. The metric element is represented by the SparkplugMetricElement Class, and it comprises the Sparkplug metric data and optionally a Sparkplug metadata (see above for their descriptions). Since this is a generic collection, it is possible that the payload contains multiple occurrences of the same metric (metric with the same name, i.e. the same string in multiple payload element keys). This scenario is allowed in Sparkplug, and can be used e.g. for historical data transfer. However, in most cases, a metric will not appear more than once in the Sparkplug payload. For this reason, the Sparkplug payload also provider properties that allow you to access the metric data and metadata for the metrics as (read-only) dictionaries. The MetricDataDictionary Property contains a read-only dictionary of Sparkplug metric data for metrics contained in the payload, keyed by metric name. Similarly, the MetadataDictionary Property contains a read-only dictionary of Sparkplug metadata for metrics contained in the payload, keyed by metric name. You can use these dictionaries to easily access metric data and metadata by the metric name.
Descriptors (or descriptor objects) are used in Rapid Toolkit for Sparkplug to provide data that allow identifying certain entity needed by the program - but they are not the entity itself, neither do they by themselves allow operations on the entity. Sparkplug descriptors are descriptors used in Rapid Toolkit for Sparkplug. For example, a Sparkplug broker descriptor provides data necessary to identify a Sparkplug broker, and is used at multiple places in the toolkit to allow specifying the broker. However, the Sparkplug broker descriptor does not contain methods e.g. to connect to or subscribe to the broker.
The Sparkplug broker descriptor, represented by the SparkplugBrokerDescriptor Class, is a descriptor for a broker in the Sparkplug system, including its connection information and custom properties. It provides a way to describe and configure a connection to the broker used in the Sparkplug system (MQTT broker). It extends the ResourceDescriptor Class to include additional properties for Sparkplug-specific configuration, such as custom property values for the broker connection.
Instances of the SparkplugBrokerDescriptor Class can be created from a descriptor string, a Url, or by copying another Sparkplug broker descriptor. The class also provides static methods and implicit operators for convenient conversion from strings and URIs. This means that (in languages that support implicit conversions, such as C# or VB.NET), you can conveniently use a URL string, such as "mqtt://myhost.mydomain.com", in place of the Sparkplug broker descriptor.
The Sparkplug connection descriptor, represented by the SparkplugConnectionDescriptor Class, is a descriptor for a connection in the Sparkplug system. It contains a Sparkplug broker descriptor (which usually specifies an MQTT broker to connect to), and a client ID to be used for the MQTT connection.
The Sparkplug specification also describes scenarios in which multiple Sparkplug brokers are used in conjunction. The Sparkplug connection descriptor is a higher-level abstraction than just the Sparkplug broker descriptor, because it allows for such advanced scenarios (although they may no tbe supported by the software currently).
There is an implicit conversion to the SparkplugConnectionDescriptor Class from the SparkplugBrokerDescriptor Class, which means that (in languages that support implicit conversions, such as C# or VB.NET), you can conveniently use a Sparkplug broker descriptor in place of the connection descriptor, which makes the distinction between them almost invisible in many cases.
Sparkplug system is a set of interconnected Sparkplug components (i.e. a Sparkplug broker, and Sparkplug edge nodes and Sparkplug host applications), which uses a common variant of Sparkplug protocol for the communication (i.e. the same or compatible Sparkplug version).
The Sparkplug system descriptor uses either the Sparkplug connection descriptor, or a Sparkplug system ID, or both, to specify the Sparkplug system to connect to. The EasySparkplugInfrastructure Class component keeps track of and maintains the set of Sparkplug systems in use.
In most concrete practical scenarios, you will use the Sparkplug connection descriptor (ConnectionDescriptor Property) to identify the Sparkplug system, and the Sparkplug system ID (SystemId Property) will be empty. The Sparkplug system ID is useful when a Sparkplug system reference needs to be distinguished from others and possibly persisted, but its actual connection data might change over time.
Sparkplug is a trademark of Eclipse Foundation, Inc. "MQTT" is a trademark of the OASIS Open standards consortium. Other related terms are trademarks of their respective owners. Any use of these terms on this site is for descriptive purposes only and does not imply any sponsorship, endorsement or affiliation.